import { Meta } from '@storybook/addon-docs/blocks';

<Meta title="For Developers/CSS Guidelines" />

# CSS Guidelines

## Trello Style Guide

For our CSS we roughly follow the [Trello CSS Style Guide](https://github.com/trello/trellisheets/blob/master/styleguide.md). 

### CSS Custom Properties

For variables, we use CSS custom properties, usually scoped to the root element

```css
:root {
  /* this is the variable: */
  --color-wnyc-red: #de1e3d;
  /* this is the design token, which should be used in the design system: */
  --color-primary: var(--color-wnyc-red);
}
```

## Components

Use the `.component-descendant-descendant` pattern for components.

```html
<div class="card" ...attributes>
  <h3 class="card-title">
    <a class="card-title-link">{{@title}}</a>
  </h3>
  <div class="card-body">{{@body}}</div>
</div>
```

## Prefixes

|prefix|name|description|
|--|--|--|
|`l-`|layout|apply these to containers to create layouts|
|`u-`|utility| used to override defaults and apply other effects|
|`mod-`|[modifiers](https://github.com/trello/trellisheets/blob/master/styleguide.md#modifiers)|never used standalone, provides variant styling for an element|
|`is-`|[states](https://github.com/trello/trellisheets/blob/master/styleguide.md#state)|never used standalone, toggled by javascript|

## Avoid `&`, the Sass 'parent selector', especially as a class prefix.
The [Sass parent selector](https://sass-lang.com/documentation/style-rules/parent-selector) can be a nice shorcut for small blocks, but once a section of code is longer than will fit on the screen, it means you have to scroll up to see what it refers to. When used as part of a class names it also breaks searching for a specific class.

```sass
/* BAD */
.my-component {
    &-message {
        color: var(--color-alert);
    }
}

/* GOOD */
.my-component {

}
  .my-component-message {
      color: var(--color-alert);
  }

```

## Breakpoints

Use the [include media](https://github.com/eduardoboucas/include-media) mixins to define breakpoints, and always define them in ascending order with the smallest size (phone) as the default.

```scss
  /* BAD */
  /* This is hard to read and prone to error */
  .my-component {
    display: grid;

    @include media("< desktop") {
      grid-template-columns: repeat(5, 1fr)
    }

    @include media("> tablet") {
      grid-template-columns: repeat(7, 1fr);
    }

    @include media("<= phone") {
      grid-template-columns: repeat(2, 1fr);
    }
  }

  /* GOOD */
  .my-component {
    display: grid;
    grid-template-columns: repeat(2, 1fr);

    @include media("> phone") {
      grid-template-columns: repeat(5, 1fr);
    }

    @include media("> tablet") {
      grid-template-columns: repeat(7, 1fr)
    }
  }

```